package com.sky.valid;

import jakarta.validation.Constraint;
import jakarta.validation.Payload;

import java.lang.annotation.Documented;
import java.lang.annotation.Retention;
import java.lang.annotation.Target;

import static java.lang.annotation.ElementType.*;
import static java.lang.annotation.ElementType.TYPE_USE;
import static java.lang.annotation.RetentionPolicy.RUNTIME;

/**
 * 列表值约束注解，用于验证列表中的值是否符合指定的条件。
 * 该注解可以应用于方法、字段、注解类型、构造函数、参数和类型使用上。
 *
 * @author Administrator
 * @Target 注解表明该注解可以应用于哪些元素类型。
 * @Retention 注解表明该注解的保留策略为运行时。
 * @Documented 注解表明该注解将被包含在文档中。
 * @Constraint 注解表明该注解是一个约束注解，并指定了其验证器。
 */
@Target({ METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER, TYPE_USE })
@Retention(RUNTIME)
@Documented
@Constraint(validatedBy = { ListValuesConstraintValidator.class })
public @interface ListValues {

    /**
     * 返回当验证失败时的错误消息，默认值为"{com.sky.valid.ListValues.message}"。
     * 这个消息可以被国际化工具解析和显示。
     *
     * @return 验证失败时的错误消息
     */
    String message() default "{com.sky.valid.ListValues.message}";

    /**
     * 返回验证约束所属于的组，默认为空组。
     * 组的概念可以用于分组验证，允许在不同的场景下应用不同的验证规则。
     *
     * @return 验证约束所属于的组
     */
    Class<?>[] groups() default { };

    /**
     * 返回与该约束注解相关的负载信息，默认为空数组。
     * 负载信息可以用于携带额外的验证逻辑或与权限系统结合使用。
     *
     * @return 与该约束注解相关的负载信息
     */
    Class<? extends Payload>[] payload() default { };

    /**
     * 返回一个整数数组，指定列表中的值必须符合的条件。
     * 例如，如果指定值为[1, 3, 5]，则意味着列表中的值必须是1、3或5之一。
     * 这个属性提供了对列表值进行预定义约束的能力，增强了验证的灵活性。
     *
     * @return 列表中的值必须符合的条件
     */
    int[] value() default {};
}
